9.17.1 Spam Package Introduction

You must read this section to understand how the Spam package works. Do not skip, speed-read, or glance through this section.

Make sure you read the section on the spam.el sequence of events. See See Extending the Spam package.

To use the Spam package, you must first run the function spam-initialize:

(spam-initialize)

This autoloads spam.el and installs the various hooks necessary to let the Spam package do its job. In order to make use of the Spam package, you have to set up certain group parameters and variables, which we will describe below. All of the variables controlling the Spam package can be found in the ‘spam’ customization group.

There are two “contact points” between the Spam package and the rest of Gnus: checking new mail for spam, and leaving a group.

Checking new mail for spam is done in one of two ways: while splitting incoming mail, or when you enter a group.

The first way, checking for spam while splitting incoming mail, is suited to mail back ends such as nnml or nnimap, where new mail appears in a single spool file. The Spam package processes incoming mail, and sends mail considered to be spam to a designated “spam” group. See Filtering Incoming Mail.

The second way is suited to back ends such as nntp, which have no incoming mail spool, or back ends where the server is in charge of splitting incoming mail. In this case, when you enter a Gnus group, the unseen or unread messages in that group are checked for spam. Detected spam messages are marked as spam. See Detecting Spam in Groups.

In either case, you have to tell the Spam package what method to use to detect spam messages. There are several methods, or spam back ends (not to be confused with Gnus back ends!) to choose from: spam “blacklists” and “whitelists”, dictionary-based filters, and so forth. See Spam Back Ends.

In the Gnus summary buffer, messages that have been identified as spam always appear with a ‘$’ symbol.

The Spam package divides Gnus groups into three categories: ham groups, spam groups, and unclassified groups. You should mark each of the groups you subscribe to as either a ham group or a spam group, using the spam-contents group parameter (see Group Parameters). Spam groups have a special property: when you enter a spam group, all unseen articles are marked as spam. Thus, mail split into a spam group is automatically marked as spam.

Identifying spam messages is only half of the Spam package’s job. The second half comes into play whenever you exit a group buffer. At this point, the Spam package does several things:

First, it calls spam and ham processors to process the articles according to whether they are spam or ham. There is a pair of spam and ham processors associated with each spam back end, and what the processors do depends on the back end. At present, the main role of spam and ham processors is for dictionary-based spam filters: they add the contents of the messages in the group to the filter’s dictionary, to improve its ability to detect future spam. The spam-process group parameter specifies what spam processors to use. See Spam and Ham Processors.

If the spam filter failed to mark a spam message, you can mark it yourself, so that the message is processed as spam when you exit the group:

$

M-d

M s x

S x

Mark current article as spam, showing it with the ‘$’ mark (gnus-summary-mark-as-spam).

Similarly, you can unmark an article if it has been erroneously marked as spam. See Setting Marks.

Normally, a ham message found in a non-ham group is not processed as ham—the rationale is that it should be moved into a ham group for further processing (see below). However, you can force these articles to be processed as ham by setting spam-process-ham-in-spam-groups and spam-process-ham-in-nonham-groups.

The second thing that the Spam package does when you exit a group is to move ham articles out of spam groups, and spam articles out of ham groups. Ham in a spam group is moved to the group specified by the variable gnus-ham-process-destinations, or the group parameter ham-process-destination. Spam in a ham group is moved to the group specified by the variable gnus-spam-process-destinations, or the group parameter spam-process-destination. If these variables are not set, the articles are left in their current group. If an article cannot be moved (e.g., with a read-only backend such as NNTP), it is copied.

If an article is moved to another group, it is processed again when you visit the new group. Normally, this is not a problem, but if you want each article to be processed only once, load the gnus-registry.el package and set the variable spam-log-to-registry to t. See Spam Package Configuration Examples.

Normally, spam groups ignore gnus-spam-process-destinations. However, if you set spam-move-spam-nonspam-groups-only to nil, spam will also be moved out of spam groups, depending on the spam-process-destination parameter.

The final thing the Spam package does is to mark spam articles as expired, which is usually the right thing to do.

If all this seems confusing, don’t worry. Soon it will be as natural as typing Lisp one-liners on a neural interface… err, sorry, that’s 50 years in the future yet. Just trust us, it’s not so bad.